// package msgpack 提供 MsgPack 格式的序列化与反序列化功能
//
// 核心目标：封装第三方 MsgPack 编解码库，提供统一的编解码器接口，简化 MsgPack 格式的序列化（Marshal）与反序列化（Unmarshal）操作。
//
// 核心组件：
//   - codec 结构体：实现了基础的编解码接口，内部通过调用第三方 msgpack 库完成实际的序列化/反序列化。
//   - DefaultCodec：默认的 codec 实例，提供便捷的编解码入口，无需手动创建实例。
//   - 包级函数 Marshal/Unmarshal：基于 DefaultCodec 实现，进一步简化调用方式。
//
// 功能特性：
//  1. 接口标准化：提供 Name/Marshal/Unmarshal 方法，符合通用编解码器的接口规范（便于在需要多格式编解码的场景中统一使用）。
//  2. 简化调用：通过默认实例和包级函数，减少使用时的代码量（如直接调用 msgpack.Marshal 即可完成编码）。
//  3. 底层可替换：封装第三方库后，若需更换 MsgPack 实现，仅需修改本包内部，不影响外部调用逻辑。
//
// 依赖说明：基于第三方库 "github.com/shamaton/msgpack/v2" 实现具体的编解码逻辑，该库兼容 MsgPack 标准格式。
package msgpack

//高效的二进制数据序列化格式
import "github.com/shamaton/msgpack/v2" // 第三方 MsgPack 编解码库，提供核心序列化/反序列化能力

// Name 定义编解码器的标识名称（固定为 "msgpack"）
// 用途：在多格式编解码场景中（如配置多种序列化方式），用于标识当前编解码器的类型
const Name = "msgpack"

// DefaultCodec 是默认的 MsgPack 编解码器实例
// 设计意图：提供开箱即用的编解码能力，避免用户每次使用时手动创建 codec 实例
var DefaultCodec = &codec{}

// codec 是 MsgPack 编解码器的具体实现结构体
// 特性：内部无状态（无字段），仅通过方法封装第三方库的编解码逻辑，线程安全（可并发使用）
type codec struct{}

// Name 返回编解码器的标识名称
// 实现意义：符合通用编解码器接口（如某些框架中定义的 Codec 接口）的规范，便于统一管理多种编解码器
func (codec) Name() string {
	return Name // 直接返回预定义的标识名称 "msgpack"
}

// Marshal 对输入值进行 MsgPack 格式序列化（编码）
// 参数：
//
//	v - 待序列化的任意类型值（可以是基础类型、结构体、切片等，需满足第三方库的序列化要求）
//
// 返回值：
//
//	[]byte - 序列化后的 MsgPack 格式字节切片
//	error - 序列化过程中发生的错误（如不支持的类型、循环引用等）
func (codec) Marshal(v interface{}) ([]byte, error) {
	// 直接调用第三方库的 Marshal 方法完成实际编码，本方法仅做一层封装
	return msgpack.Marshal(v)
}

// Unmarshal 将 MsgPack 格式的字节切片反序列化为目标类型（解码）
// 参数：
//
//	data - 待反序列化的 MsgPack 格式字节切片
//	v - 接收反序列化结果的指针（必须为指针类型，否则无法写入结果，会返回错误）
//
// 返回值：
//
//	error - 反序列化过程中发生的错误（如数据格式错误、类型不匹配、v 非指针等）
func (codec) Unmarshal(data []byte, v interface{}) error {
	// 直接调用第三方库的 Unmarshal 方法完成实际解码，本方法仅做一层封装
	return msgpack.Unmarshal(data, v)
}

// Marshal 包级别的 MsgPack 序列化函数（基于 DefaultCodec 实现）
// 设计意图：提供更简洁的调用方式，无需通过 DefaultCodec 实例，直接调用 msgpack.Marshal 即可
// 参数与返回值：同 codec.Marshal 方法
func Marshal(v interface{}) ([]byte, error) {
	return DefaultCodec.Marshal(v)
}

// Unmarshal 包级别的 MsgPack 反序列化函数（基于 DefaultCodec 实现）
// 设计意图：提供更简洁的调用方式，无需通过 DefaultCodec 实例，直接调用 msgpack.Unmarshal 即可
// 参数与返回值：同 codec.Unmarshal 方法
func Unmarshal(data []byte, v interface{}) error {
	return DefaultCodec.Unmarshal(data, v)
}
